

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="zh-CN" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="zh-CN" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>规范 &mdash; WeIdentity  文档</title>
  

  
  
  
  

  

  
  
    

  

  <link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/theme_overrides.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/index.css" type="text/css" />
    <link rel="index" title="索引" href="../../genindex.html" />
    <link rel="search" title="搜索" href="../../search.html" /> 

  
  <script src="../../_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

          
            <a href="../../index.html" class="icon icon-home"> WeIdentity
          

          
          </a>

          
            
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <p class="caption"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../README.html">什么是 WeIdentity？</a></li>
<li class="toctree-l1"><a class="reference internal" href="../one-stop-experience.html">WeIdentity 一站式体验</a></li>
<li class="toctree-l1"><a class="reference internal" href="../terminologies.html">术语</a></li>
<li class="toctree-l1"><a class="reference internal" href="../use-cases.html">使用场景</a></li>
<li class="toctree-l1"><a class="reference internal" href="../weidentity-spec.html">WeIdentity 规范</a></li>
<li class="toctree-l1"><a class="reference internal" href="../weidentity-installation.html">WeIdentity Java SDK 安装部署</a></li>
<li class="toctree-l1"><a class="reference external" href="https://weidentity.readthedocs.io/projects/javasdk/zh_CN/latest/">WeIdentity Java SDK 文档</a></li>
<li class="toctree-l1"><a class="reference internal" href="../weidentity-sample.html">WeIdentity Sample 开发样例</a></li>
<li class="toctree-l1"><a class="reference internal" href="../miscellaneous.html">杂项</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../weidentity-rest.html">WeIdentity RestService</a></li>
<li class="toctree-l1"><a class="reference internal" href="../weidentity-endpoint.html">WeIdentity Endpoint Service</a></li>
<li class="toctree-l1"><a class="reference internal" href="../weidentity-contract-design.html">WeIdentity 智能合约设计与实现</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../index.html">WeIdentity</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="../../index.html">Docs</a> &raquo;</li>
        
      <li>规范</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="../../_sources/docs/styleguides/styleguides.md.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="">
<span id="id1"></span><h1>规范<a class="headerlink" href="#" title="永久链接至标题">¶</a></h1>
<div class="section" id="">
<span id="id2"></span><h2>基本要求：<a class="headerlink" href="#" title="永久链接至标题">¶</a></h2>
<ul>
<li><p>所有文件必须使用 UTF-8 编码，且文件格式为 unix 文件格式，而不能使用 GBK 和 dos。</p></li>
<li><p>所有代码请统一使用4个空格作为缩进。</p></li>
<li><p>代码文件中，每行最多100个字符（xml文件每行字符可以超过100个）。</p></li>
<li><p>双斜杠的注释 <code class="docutils literal notranslate"><span class="pre">//</span></code> 只能在函数内部使用，其他注释请使用:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/**</span>
<span class="o">*/</span>
</pre></div>
</div>
</li>
<li><p>所有英文术语的大小写敏感，并注意拼写，请按照<a class="reference external" href="../terminologies.rst">术语表</a>的术语定义来使用。</p></li>
<li><p>关于空行</p>
<ul>
<li><p>函数内部，一般使用空行分割不同的逻辑，例如一个函数可能流程有大概 4 步，则 4 步中的每步之间，用一行空行分割。</p></li>
<li><p>类里面的最后一条语句和最后一个大括号 <code class="docutils literal notranslate"><span class="pre">}</span></code> 之间不能有空行。</p></li>
<li><p>【建议】类定义文件最后有一行空行，也就是在最后一个 <code class="docutils literal notranslate"><span class="pre">}</span></code> 后有一行空行。</p></li>
<li><p>【建议】函数里面的代码的最后一行和 <code class="docutils literal notranslate"><span class="pre">}</span></code> 之间不能有空行，例如最后一个return和 <code class="docutils literal notranslate"><span class="pre">}</span></code> 之间不能有空行。</p></li>
<li><p>【建议】类成员变量之间需要有空行分割。</p></li>
<li><p>【建议】函数申明（定义）后 的第一个括号 <code class="docutils literal notranslate"><span class="pre">{</span></code> 跟第一行代码之间，建议有一行空行。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">public</span> <span class="n">ResponseData</span><span class="o">&lt;</span><span class="n">CreateWeIDResult</span><span class="o">&gt;</span> <span class="n">createWeID</span><span class="p">(</span><span class="n">CreateWeIDArgs</span> <span class="n">createWeIDArgs</span><span class="p">)</span> <span class="p">{</span>

    <span class="n">ResponseData</span><span class="o">&lt;</span><span class="n">CreateWeIDResult</span><span class="o">&gt;</span> <span class="n">responseData</span> <span class="o">=</span> <span class="n">new</span> <span class="n">ResponseData</span><span class="o">&lt;</span><span class="n">CreateWeIDResult</span><span class="o">&gt;</span><span class="p">();</span>
    <span class="k">return</span> <span class="n">null</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
</ul>
</li>
</ul>
</div>
<hr class="docutils" />
<div class="section" id="">
<span id="id3"></span><h2>文件名命名规范<a class="headerlink" href="#" title="永久链接至标题">¶</a></h2>
<ul class="simple">
<li><p>全小写。</p></li>
<li><p>单词间使用破折号 <code class="docutils literal notranslate"><span class="pre">-</span></code> 进行分割，例如 <code class="docutils literal notranslate"><span class="pre">verify-credential.md</span></code>。</p></li>
<li><p>JAVA 代码文件可以不用按照上面的规则，而按 JAVA 原有规范。</p></li>
</ul>
</div>
<hr class="docutils" />
<div class="section" id="">
<span id="id4"></span><h2>变量命名规范<a class="headerlink" href="#" title="永久链接至标题">¶</a></h2>
<ul class="simple">
<li><p><strong>WeIdentity DID KEY</strong></p></li>
</ul>
<p>SDK 侧（例如JAVA SDK， C++ SDK）都使用 WeIdentity DID 作为 key。通过 SDK 解析为地址后，在合约中使用地址作为 key，取名 weAddress。类型使用 <code class="docutils literal notranslate"><span class="pre">address</span></code>。</p>
<ul class="simple">
<li><p><strong>id, Id or ID?</strong></p></li>
</ul>
<p>单词中出现的 “id”，请统一使用 Id （例如变量名 weId，类名就是 WeId*，例如 WeIdUtils 等），而不是用 id，ID 等。例外情况如下：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>* 如果是在单词最前面，则可以使用 id（因驼峰命名法）。
* 如果是在常量名里面，则因为全部字母都是大写，所以使用 ID。
</pre></div>
</div>
<ul class="simple">
<li><p><strong>区分 acronym 和 abbreviation</strong></p></li>
</ul>
<p>例如 HTTP 是 “Hyper Text Transport Protoco” 的 acronym，而 id 是 identity 的 abbreviation。
对 acronym，则在命名中所有字母都保留大写，而对 abbreviation 则在驼峰命名中可以使用 Id 或者 id（位于单词最前面）。</p>
<p>例如类名：HelperHTTPRequest，对应的实例化变量：helperHTTPRequest。
一般建议不要把 acronym 放在变量命名单词的最前面，否则这个变量的第一个字母就不是小写了。例如有个变量您可以取名为 niceHTTPRequest，而不是叫 HTTPRequest（看起来就不像是变量名了）。</p>
<ul class="simple">
<li><p><strong>统一的变量命名</strong></p></li>
</ul>
<p>| Key | Type | Description |
| :—: | :—: |:——|
| weId |string| weId 变量名 |
| weAddress |合约中使用 address/java 中对应 string| weId 转换为 address 后的名字 |
| cptId | uint| CPT 类型，例如 cpt101，则值为 101 |
| created |int| 创建时间|
| updated |int| 更新时间 |
| logger |Logger| java 类里面的 logger 变量 |</p>
<ul class="simple">
<li><p><strong>常见技术名词</strong></p></li>
</ul>
<p>| Key | Description |
| :—: | :——|
| SDK | 注意是全部大写，不是 Sdk，也不是 sdk |</p>
</div>
<hr class="docutils" />
<div class="section" id="java">
<span id="java"></span><h2>JAVA 代码规范<a class="headerlink" href="#java" title="永久链接至标题">¶</a></h2>
<ul>
<li><p>JAVA 代码对调用者暴露的接口，请按照 javadoc 的模式注释。</p></li>
<li><p>函数的声明（函数定义）这一行如果超过了 100 个字符，请按每行一个参数的方式缩进（第一个参数从”函数名定义行“的下一行开始定义），且参数定义行相对于“函数名定义行”多缩进 4 个空格，例子如下：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">//</span><span class="n">java函数定义的例子</span>
<span class="n">private</span> <span class="n">static</span> <span class="nb">int</span> <span class="n">resolveAttributeEvent</span><span class="p">(</span>
    <span class="n">String</span> <span class="n">weid</span><span class="p">,</span>
    <span class="n">TransactionReceipt</span> <span class="n">receipt</span><span class="p">,</span>
    <span class="n">GetWeIDDocumentResult</span> <span class="n">result</span><span class="p">)</span> <span class="p">{</span>
    <span class="o">//</span> <span class="n">logic</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><p>函数调用如果超过了 100 个字符，请按每行一个参数的方式缩进，例子如下：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TransactionReceipt</span> <span class="n">transactionReceipt</span> <span class="o">=</span> <span class="n">cptController</span><span class="o">.</span><span class="n">registerCpt</span><span class="p">(</span>
    <span class="n">publisher</span><span class="p">,</span>
    <span class="n">intArray</span><span class="p">,</span>
    <span class="n">bytes32Array</span><span class="p">,</span>
    <span class="n">jsonSchema</span><span class="p">,</span>
    <span class="n">rsvSignature</span><span class="o">.</span><span class="n">getV</span><span class="p">(),</span>
    <span class="n">rsvSignature</span><span class="o">.</span><span class="n">getR</span><span class="p">(),</span>
    <span class="n">rsvSignature</span><span class="o">.</span><span class="n">getS</span><span class="p">()</span>
<span class="p">)</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">WeIdConstant</span><span class="o">.</span><span class="n">TRANSACTION_RECEIPT_TIMEOUT</span><span class="p">,</span> <span class="n">TimeUnit</span><span class="o">.</span><span class="n">SECONDS</span><span class="p">);</span>
</pre></div>
</div>
</li>
<li><p>import 顺序：按库的类型，分成多个section，每个section之间空行分割，section内部按字母序排列，见下面的例子。</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>1. import java/javax相关库
2. import 第三方库
3. import 当前库的class 和 interface等
4. import static
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">java.</span><span class="o">*</span>
<span class="kn">import</span> <span class="nn">javax.</span><span class="o">*</span>

<span class="kn">import</span> <span class="nn">thirdparty</span><span class="o">-</span><span class="n">libraries</span>

<span class="kn">import</span> <span class="nn">com.webank.weid.</span><span class="o">*</span>

<span class="kn">import</span> <span class="nn">static</span> <span class="o">*</span>
</pre></div>
</div>
</li>
<li><p>以上面列出的规范优先，其余遵守 <a class="reference external" href="https://google.github.io/styleguide/javaguide.html">Google JAVA 代码规范</a>。</p></li>
</ul>
</div>
<hr class="docutils" />
<div class="section" id="solidity">
<span id="solidity"></span><h2>Solidity 代码规范<a class="headerlink" href="#solidity" title="永久链接至标题">¶</a></h2>
<ul>
<li><p>Solidity 因为在函数申明的结尾处可以有 modifier 等关键字，所以遵循 Solidity 本身的规范。</p>
<p>注：soliditiy 因为 solidity 代码规范，所以函数的左括号是在跟 “function” 在同级，而不是放在“上一行”（这一点跟 JAVA 不一致）。</p>
</li>
</ul>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="c1">// solidity 的例子</span>
<span class="kd">function</span> <span class="nx">thisFunctionNameIsReallyLong</span><span class="p">(</span>
    <span class="nx">address</span> <span class="nx">x</span><span class="p">,</span>
    <span class="nx">address</span> <span class="nx">y</span><span class="p">,</span>
    <span class="nx">address</span> <span class="nx">z</span><span class="p">,</span>
<span class="p">)</span>
    <span class="kr">public</span>
    <span class="nx">onlyowner</span>
    <span class="nx">priced</span>
    <span class="nx">returns</span> <span class="p">(</span><span class="nx">address</span><span class="p">)</span>
<span class="p">{</span>
    <span class="nx">doSomething</span><span class="p">();</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="c1">//函数调用的例子</span>
<span class="kr">int</span> <span class="nx">ret</span> <span class="o">=</span> <span class="nx">thisFunctionCallIsReallyLong</span><span class="p">(</span>
    <span class="nx">longArgument1</span><span class="p">,</span>
    <span class="nx">longArgument2</span><span class="p">,</span>
    <span class="nx">longArgument3</span>
<span class="p">);</span>
</pre></div>
</div>
<ul class="simple">
<li><p>以上面列出的规范优先，其余遵守 <a class="reference external" href="https://solidity.readthedocs.io/en/latest/style-guide.html">Solidity 代码规范</a>。</p></li>
<li><p>智能合约最佳实践： <a class="reference external" href="https://github.com/ConsenSys/smart-contract-best-practices">smart-contract-best-practices</a>。</p></li>
<li><p>智能合约静态扫描工具： <a class="reference external" href="https://github.com/duaraghav8/Solium">Linter-for-Solidity</a>。</p></li>
</ul>
</div>
</div>


           </div>
           
          </div>
          <footer>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright (2018) WeBank Co., Ltd.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    
    
      <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
        <script src="../../_static/jquery.js"></script>
        <script src="../../_static/underscore.js"></script>
        <script src="../../_static/doctools.js"></script>
        <script src="../../_static/language_data.js"></script>
        <script src="../../_static/translations.js"></script>
    

  

  <script type="text/javascript" src="../../_static/js/theme.js"></script>

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>